home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 22 / AACD 22.iso / CDTools / Players / DeliTracker / Developer / Developer.eng next >
Text File  |  1995-07-18  |  32KB  |  775 lines
  1.  
  2.  
  3.                  $VER: Developer.eng V2.17 (18.07.1995)
  4.                    Copyright 1995 by Delirium Softdesign
  5.                       (Peter Kunath and Frank Riffel)
  6.  
  7.                   DeliTracker Development Documentation
  8.  
  9.  
  10.   1.OVERVIEW
  11.  
  12.   2.PLAYERS
  13.    2.1 Normal Players
  14.    2.2 Custom Modules
  15.    2.3 Interrupts
  16.  
  17.   3.GENIES
  18.    3.1 Generic Kind
  19.    3.2 Converter
  20.    3.3 Decruncher
  21.    3.4 NotePlayer
  22.  
  23.   4.TAGS
  24.  
  25.   5.DELITRACKER SUPPORT FUNCTIONS
  26.  
  27.  
  28.   1.OVERVIEW
  29.  
  30.   DeliTracker can be extended with external code. From DOS sight external
  31.   code for DeliTracker is nothing else than an executable object file
  32.   that contains a characteristic structure at the beginning of first code
  33.   hunk. When DeliTracker has loaded such external code it evaluates this
  34.   structure. It consists of three parts: one longword of code, two longs
  35.   used as identifier and at last a pointer to a taglist. The first long
  36.   usually contains a moveq #-1,d0 and a rts instruction. This prevents a
  37.   system crash if a user accidentally tries to run a normal genie or player
  38.   from shell. To get a program that works without DeliTracker, too, you
  39.   can change this to a bra.w to your own startup code. You should use the
  40.   PLAYERHEADER macro from 'deliplayer.i' to create this structure. It has
  41.   two parameters: a pointer to the tag array and a pointer to the optional
  42.   startupcode.
  43.  
  44.     PLAYERHEADER <tagarray>,[startup]
  45.  
  46.         tagarray        Pointer to a tag array, terminated with TAG_DONE.
  47.         startup         Pointer to optional startup code. Only set if you
  48.                         need to make the code run without DeliTracker.
  49.                         This option is sometimes useful for debugging
  50.                         purposes.
  51.                         Note: In case the startup code is called you have
  52.                         to do anything by your own! The startup option
  53.                         does not make sense in most cases. Use rarely.
  54.  
  55.   This taglist contains all informations that DeliTracker must know. We
  56.   have choosen to use a tag array because it is extremely flexible and
  57.   extensible. For the other direction the external code has the limited
  58.   ability to check the internal program state by looking at the DeliTracker
  59.   Global structure. It can also take advance of inbuild support functions.
  60.   At the moment DeliTracker knows two different types of external code:
  61.  
  62.         1) Players they have the task to identify and play a modules.
  63.  
  64.         2) Genies can perform several other things. This includes module
  65.            conversion, extended decrunch support and information display.
  66.  
  67.   Both types can run synchronusly or asynchronusly. The term synchronuns
  68.   means that the player or the genie is not running as seperate task.
  69.   DeliTracker will communicate with the genie or player using real fuction
  70.   calls (jsr). In asynchronus mode DeliTracker will spawn an own process
  71.   for the player or genie. Now DeliTracker uses a message based interface
  72.   to "call" the functions of the external code. In general genies tend to
  73.   run asynchronus whereas player run synchronous. If a player or genie is
  74.   running asynchronously a CTRL-C signal must terminate it. As you see
  75.   DeliPlayers and DeliGenies are very similiar. Indeed DeliTracker handles
  76.   them in the same way but of course in two sperate lists. All external
  77.   code that has set the DTP_CustomPlayer, DTP_Check1 or DTP_Check2 tag is
  78.   a player. The rest is threated as genie.
  79.  
  80.   If a player or genie has a GUI it should offer the following menu items:
  81.  
  82.         Project
  83.                 About      A ?  Displays a short info
  84.                 ==============
  85.                 Save Prefs A S  Save the current settings as default
  86.                 ==============
  87.                 Hide       A H  Hide the GUI
  88.                 ==============
  89.                 Quit       A Q  Remove the Player/Genie (same as CTRL-C)
  90.  
  91.         Settings
  92.                 Activate   A A  Activates the window if the GUI is opened
  93.                 Popup      A P  Opens the GUI after loading
  94.                 ==============
  95.                 Other settings  Other genie specific settings, see the
  96.                 ··············  particular genie documentation.
  97.  
  98.   Some general things:
  99.  
  100.   A good point to start with is to read the supplied example sources. To
  101.   get an idea how DeliTracker calls the player routines see 'Testplayer.s'.
  102.   Configuration files should not be saved to ENV:. Instead they should be
  103.   stored in DeliTracker's default configuration directory. The path of this
  104.   directory can be found in the 'DeliConfig' ENV-Variable. If this variable
  105.   is not set the configuration should be saved to 'PROGDIR:DeliConfig'.
  106.   Your player should not change the LED (Filter) state because DeliTracker
  107.   will handle this. Besides the interrupt routine any other subroutine may
  108.   trash any register. When DeliTracker calls a player function (exept the
  109.   interrupt routine) a5 will contain the address to the global player data
  110.   structure (Base).
  111.  
  112.  
  113.   2.PLAYERS
  114.  
  115.   It is not difficult to adapt a player if you have the replayroutine.
  116.   You only need to write some interfacecode. DeliTracker has some helpful
  117.   builtin routines that will make this job a lot easier. To adapt a new
  118.   soundsystem you need the replayroutine of that soundsystem, and some
  119.   modules for testing the adaption. At the beginning of an external
  120.   player you can find the characteristic playerstructure. DeliTracker
  121.   distinguishes between two kinds: normal players and custom modules.
  122.  
  123.     2.1 Normal Players
  124.  
  125.     Normal players identify and play modules. They must allways have a
  126.     check routine. This is the schematic structure of a normal player:
  127.  
  128.         { player header }       identifies the objectfile
  129.         { tag array     }       description of the playerfuntions.
  130.         { interfacecode }       playername/registerconversion/checkcode...
  131.         { replaycode    }       replay code itself
  132.         { optional data }       optional data
  133.  
  134.     In order to recognize different moduleformats every player must contain
  135.     a specific routine, that tells DeliTracker if the player can play this
  136.     module or not. This routine has the task to check certain positions in
  137.     the module that are identical in every module (like 'M.K.' at offset
  138.     $438 in NoiseTracker modules) or significant assembler instructions (if
  139.     the module contains the player). Testing against one or two branches or
  140.     jumps is NOT enough, cause many modules with player have branchtables at
  141.     the beginning of the module. If the player recognizes a wrong module, it
  142.     is likely that a system crash will result! So be very careful with the
  143.     ckeck routine. There are two different types of check functions but your
  144.     player must use exactly one check routine.
  145.  
  146.     a) DTP_Check1: The check function is called after DeliTracker has
  147.     loaded 1K of the file. This has the advantage that you can implement
  148.     players that can load the module by itself. The disadvantage is that
  149.     you don't profit from the internal packsupport and of course it is
  150.     more complex to write such players. Use this type only where you must
  151.     load the module by yourself!
  152.  
  153.     b) DTP_Check2: The check function is called after the module is loaded
  154.     and decrunched. This is the easy way. All memory allocation, loading
  155.     and decrunching is done by DeliTracker.
  156.  
  157.     Regardless of the playertype the checkfunction must return d0.l=0 if
  158.     the player can handle this module or d0.l<>0 if not.
  159.  
  160.  
  161.     2.2 Custom modules
  162.  
  163.     This is a very special thing: Custom modules contain replay and sound
  164.     data, both relocatable. They don't contain a check routine. With the
  165.     custom module interface you can adapt almost every module. If you have
  166.     more modules with the same replay routine we suggest to write an own
  167.     player for this moduleformat.
  168.  
  169.         { player header }       identifies the objectfile
  170.         { tag array     }       description of the playerfuntions.
  171.         { interfacecode }       playername/registerconversion/checkcode...
  172.         { replaycode    }       replay code itself
  173.         { optional data }       optional data
  174.         { SOUND DATA    }       music data (the module)
  175.  
  176.  
  177.     2.3 Interrupts
  178.  
  179.     Players can be divided in two categories:
  180.  
  181.     a) Player that uses the internal timer interrupt from DeliTracker
  182.  
  183.      Advantage: The player is independent from the selected videomode
  184.         The player has automatically the faster/slower function. No expense
  185.         for interrupthandling (interrupt structure and the insert/remove
  186.         code). Compatible with the serial.device.
  187.  
  188.     b) Player that generates their own interrupt
  189.  
  190.      Advantage: You can use other interrupt sources (like AudioIRQ)
  191.  
  192.      Disadvantage: You have to handle the interrupts by yourself, and if
  193.         you use VBlank the player is not independent to the videomode.
  194.  
  195.     If you use your own timerinterrupt you should allocate CIAB because
  196.     under 2.x the CIAA is used by the system. Do not to run the soundcode
  197.     directly in the timerinterrupt. Instead you should Cause() a SoftInt in
  198.     the timer interrupt and execute the routine in the SoftInt. This is to
  199.     assure maximum compatibility for modem users because the SoftInt has a
  200.     lower priority thant the RBF interrupt. Beware of writing directly to
  201.     the 680x0 intvectors! You should use AddIntServer() or SetIntVector()
  202.     from the OS.
  203.  
  204.  
  205.   3.GENIES
  206.  
  207.   As said Genies can 'help' DeliTracker to perform different tasks. At the
  208.   moment four different functionalitys are distinguished: output of notes
  209.   (not to be mixed up with players), decrunching and conversion of Modules
  210.   and finaly acting on the current module.
  211.  
  212.     3.1 Generic Kind
  213.  
  214.     This kind of genie can do many things (e.g display informations). Of
  215.     course neither the module nor DeliTracker's global structure may be
  216.     changed to obtain the desired informations. Usually this type will use
  217.     DTP_InitPlay/DTP_EndPlay to get notified when the module changes.
  218.  
  219.     3.2 Converter
  220.  
  221.     This genie has the task to change a module. E.g. it can convert one
  222.     format into another or change the size of the module. It is identified
  223.     by the special tag DTP_Convert. This tag contains the address of the
  224.     conversion function. DeliTracker will call this function at the right
  225.     time.
  226.  
  227.     3.3. Decruncher
  228.  
  229.     This kind of genie enhances DeliTracker's dtg_LoadFile() function.
  230.     The calling interface is not documented yet beacuse this part may
  231.     still change.
  232.  
  233.     3.4 Noteplayer
  234.  
  235.     This genie type will convert/redirect 'Notes' to the actualy used
  236.     audiohardware. The interface is not documented yet beacuse this
  237.     part is still under development.
  238.  
  239.  
  240.   4.TAGS
  241.  
  242.   In addition to the system tags (TAG_DONE, TAG_IGNORE, TAG_MORE, TAG_SKIP)
  243.   this tags may be used:
  244.  
  245.   DTP_CustomPlayer (BOOL) - this tag identifies a player as customplayer.
  246.                 If this tag is used the following tags are ignored:
  247.                                 DTP_PlayerVersion
  248.                                 DTP_PlayerName
  249.                                 DTP_Creator
  250.                                 DTP_Check1
  251.                                 DTP_Check2
  252.                                 DTP_ExtLoad
  253.                                 DTP_Config
  254.                                 DTP_UserConfig
  255.  
  256.   DTP_RequestDTVersion (UWORD) - only if the DeliTracker version is greater
  257.                 than or equal to the requested version (ti_Data) will
  258.                 DeliTracker accept the player. If your player uses
  259.                 functions that were introduced in later revisions of
  260.                 DeliTracker you must set this tag according to the version
  261.                 that introduced this function.
  262.  
  263.   DTP_RequestKickVersion (ULONG) - set this tag to the required OS version.
  264.  
  265.   DTP_PlayerVersion (ULONG) - Tag that contains the version (high word) and
  266.                 revision number (low word) of the player. If there are two
  267.                 players with same name the player with the higher version
  268.                 is used.
  269.  
  270.   DTP_PlayerName (STRPTR) - ti_Data contains a pointer to the playername.
  271.                 This string may be as long as you wish, but only the first
  272.                 24 chars are actually used. This tag must exist !
  273.  
  274.   DTP_Creator (STRPTR) - pointer to the author/adaptor name. This string
  275.                 is visible in the prefs window if the player is selected.
  276.                 The string may contain $A as line separator.
  277.  
  278.   DTP_Check1 (FPTR) - pointer to a module identification routine. This
  279.                 routine is called after the first 1024 bytes of the module
  280.                 are loaded. If the module is shorter, the rest will contain
  281.                 zero. If the routine recognizes the moduleformat it must
  282.                 return d0=0 else d0<>0.
  283.  
  284.   DTP_Check2 (FPTR) - pointer to a module identification routine. This
  285.                 routine is called after the complete module is loaded (and
  286.                 decrunched). If the routine recognizes the module it must
  287.                 return d0=0 else d0<>0.
  288.  
  289.   DTP_Extload (FPTR) - pointer to a optional loadroutine for modules. If
  290.                 an error occurs return d0<>0 else d0=0. Please remember to
  291.                 free all allocated resources (memory, locks,...), because
  292.                 no further player function is called.
  293.  
  294.   DTP_Interrupt (FPTR) - pointer to a interruptroutine. This routine is
  295.                 called every 1/50 sec. via a timer.device. Note: your
  296.                 interruptroutine is not executed in the timerinterrupt
  297.                 itself. This is the standard method for gaining the
  298.                 correct playspeed regardless of the videomode. If the
  299.                 DTP_Faster/DTP_Slower pointers are not supplied,
  300.                 DeliTracker emulates this by changing the interrupt
  301.                 frequency. If this tag doesn't exist, you must supply
  302.                 DTP_StartInt/DTP_StopInt.
  303.  
  304.   DTP_Stop (FPTR) - pointer to optional stop routine. If this tag does not
  305.                 exist, DeliTracker uses the following standard method:
  306.                         stop interrupt (DTP_StopInt)
  307.                         cleanup sound (DTP_EndSnd)
  308.                         reinitialize the song (DTP_InitSnd)
  309.                 This routine will stop playing the song, reset the
  310.                 'patterncounter' to the begin and change the playspeed
  311.                 to default. This means that the interrupt is started
  312.                 again and the song should begin to play from the
  313.                 beginning.
  314.  
  315.   DTP_Config (FPTR) - pointer to an optional initialising routine. This
  316.                 routine is only called once after the player is loaded.
  317.                 Purpose: The player could load a specific configfile.
  318.                 Must return d0=0 if all is ok else d0<>0. In case of an
  319.                 error DeliTracker will remove this player.
  320.  
  321.   DTP_UserConfig (FPTR) - pointer to a optional initialising routine. This
  322.                 routine is called if the user selects the 'Config' button
  323.                 in the prefswindow. Purpose: The player could open a player
  324.                 specific configwindow for setting special options (e.g
  325.                 instrumentpath for a sonix player) and saving them into a
  326.                 configfile.
  327.  
  328.   DTP_SubSongRange (FPTR) - Obsolete, please use DTP_NewSubSongRange!
  329.                 This tag should be supplied if the player supports
  330.                 multimodules. ti_Data points to a function that returns
  331.                 in d0 the minimum and in d1 the maximum subsong number.
  332.  
  333.   DTP_InitPlayer (FPTR) - pointer to an initialising routine, that is
  334.                 called if a module is loaded successfully. Must return
  335.                 d0=0 if all is ok else d0<>0. The audioallocation must be
  336.                 done here. (DeliTracker has a function that does the
  337.                 allocation.) If the player supports subsongs it has to set
  338.                 dtg_SndNum(a5) to the first subsongnumber. If a routine
  339.                 for DTP_SubSongRange exists, DeliTracker performs this for
  340.                 you and you may omit the initialization for dtg_SndNum(a5).
  341.  
  342.   DTP_EndPlayer (FPTR) - pointer to a cleanuproutine, that is called if the
  343.                 module is removed from memory. Audiochannels have to be
  344.                 freed here. (Use the DeliTracker internal supportroutine)
  345.  
  346.   DTP_InitSound (FPTR) - pointer to an optional initialising routine. This
  347.                 routine has the task to (re)initialize the module. If the
  348.                 interrupt is started the song should begin to play at the
  349.                 beginning.
  350.  
  351.   DTP_EndSound (FPTR) - pointer to an optional cleanuproutine. For example
  352.                 it can be used to reset the volumeregister or the audiodma.
  353.  
  354.   DTP_StartInt (FPTR) - pointer to an initialising routine, that must exist
  355.                 if DTP_Interrupt doesn't exist. It has the task to start
  356.                 the sound.
  357.  
  358.   DTP_StopInt (FPTR) - pointer to a cleanuproutine, that must exist if
  359.                 DTP_Interrupt doesn't exist. It has the task to stop the
  360.                 sound.
  361.  
  362.   DTP_Volume (FPTR) - pointer to function that sets the volume. This
  363.                 function is called every time the volume is changed (via
  364.                 arexx or slider) and once at the initialising phase of the
  365.                 module (before DTP_InitSnd is called). The mastervolume can
  366.                 be found in dtg_SndVol(a5). The mastervolume is the highest
  367.                 volume allowed. The effective volume can be calculated
  368.                 using the following formula:
  369.                         VOL_eff=( ( MASTERVOLUME*modulevolume ) >>6 ).
  370.                 See also the example sources.
  371.  
  372.   DTP_Balance (FPTR) - pointer to a function that sets the balance. This
  373.                 function is called every time the balance is changed (via
  374.                 arexx or slider) and once at the initialising phase of the
  375.                 module (before tf_InitSnd is called). The balance for the
  376.                 left channel can be found in dtg_SndLBal(a5), for the right
  377.                 channel in dtg_SndRBal(a5). Note: All players that support
  378.                 balance are capable of volume too! Then you must use the
  379.                 same routine for both operations. The mastervolume for the
  380.                 left channels can be calculated with this formula:
  381.                     LeftMaster =( ( dtg_Volume(a5)*dtg_SndLBal(a5) ) >>6 ).
  382.                 For the right channels the formula is similar.
  383.  
  384.   DTP_Faster (FPTR) - pointer to a function that increases the playspeed.
  385.  
  386.   DTP_Slower (FPTR) - pointer to a function that decreases the playspeed.
  387.  
  388.   DTP_NextPatt (FPTR) - pointer to a function that increases the
  389.                 patternpointer.
  390.  
  391.   DTP_PrevPatt (FPTR) - pointer to a function that decreases the
  392.                 patternpointer.
  393.  
  394.   DTP_NextSong (FPTR) - pointer to a function that increases the
  395.                 subsongcounter (only if the subsong exists).
  396.  
  397.   DTP_PrevSong (FPTR) - pointer to a function that decreases the
  398.                 subsongcounter (only if the subsong exists).
  399.  
  400.   ;--- tags in revision 14 or higher (distributed as Release 1.35) ---
  401.  
  402.   DTP_SubSongTest (FPTR) - The tag is only evaluated if DTP_SubSongRange
  403.                 exits too. ti_Data points to a routine that returns
  404.                 a boolean value. This indicates if the subsong number
  405.                 dtg_SubNum(a5) is valid (d0=0) or not (d0<>0). This tag
  406.                 is only necessary for players where not every subsong
  407.                 in the subsong range is existant.
  408.  
  409.   ;--- tags in revision 16 or higher (distributed as Release 2.01) ---
  410.  
  411.   DTP_NewSubSongRange (APTR) - enhanced replacement for DTP_SubSongRange.
  412.                 This tag should be supplied if the player supports
  413.                 multimodules. ti_Data is  a pointer to an array of three
  414.                 WORDs: The first word contains the default subsong that
  415.                 should be played at first. The second contains the minimum
  416.                 and the third the maximum subsong number. In most cases
  417.                 the first and the second word will be equal.
  418.  
  419.   DTP_DeliBase (APTR) - the address of a pointer where DT will
  420.                 store a pointer to the DeliGlobals
  421.  
  422.   DTP_Flags (ULONG) - contains various Flags.
  423.                 Currently the following flags are defined:
  424.                 PLYF_CUSTOM     - player is a customplayer
  425.                 PLYF_SONGEND    - this player supports songend
  426.                 PLYF_ANYMEM     - modules of this player can be stored
  427.                                   anywhere, chipmem is not required
  428.  
  429.   DTP_CheckLen (ULONG) - Length of the check Code. Set this tag only if
  430.                 the check code is PC-relative and reentrant! If set this
  431.                 enables DeliTracker to swap out the player code.
  432.  
  433.   DTP_Description (APTR) - Pointer to a string that describes what this
  434.                 player/genie does and what special features it has. The
  435.                 string may contain $A as line separator.
  436.  
  437.   DTP_Decrunch (FPTR) - private, still under development!
  438.  
  439.   DTP_Convert (FPTR) - pointer to a module conversion routine. This routine
  440.                 is called after a module has been loaded and decrunched. It
  441.                 has the task to convert the module from one to another
  442.                 module format. The conversion routine works usually the
  443.                 following way:  1) recognize source format
  444.                                 2) allocate memory for target format with
  445.                                 dtg_AllocListData().
  446.                                 3) convert source to target format
  447.                 This routine returns NULL if a conversion took place
  448.                 (success) and -1 in any other case (error). Make sure that
  449.                 the conversion routine does not change the source module!
  450.                 Note: for temporary memory allocations you can use the
  451.                 exec memoryhandling functions as well. But be aware that
  452.                 memory of the final converted module must be allocated with
  453.                 DeliTracker's dtg_AllocListData()!
  454.  
  455.   DTP_NotePlayer (APTR) - private, still under development!
  456.  
  457.   DTP_NoteStruct (APTR) - private, still under development!
  458.  
  459.   DTP_NoteInfo (APTR) - private, still under development!
  460.  
  461.   DTP_NoteSignal (FPTR) - private, still under development!
  462.  
  463.   DTP_Process (FPTR) - pointer to process entry code. If this tag is set
  464.                 DeliTracker will start the player or genie as seperate
  465.                 process.
  466.  
  467.   DTP_Priority (BYTE) -  priority of the created process. Only in
  468.                 conjunction with DTP_Process possible. If this tag is
  469.                 omitted, the new process will have the same priority
  470.                 as DeliTracker.
  471.  
  472.   DTP_StackSize (ULONG) - stack size of the created process. Only in
  473.                 conjunction with DTP_Process possible. If this tag is
  474.                 omitted, the stacksize will be set to 4096 bytes.
  475.  
  476.   DTP_MsgPort (APTR) - address of a pointer where DT will store the port
  477.                 address to which DT will send it's messages. Only in
  478.                 conjunction with DTP_Process useful.
  479.  
  480.   DTP_Appear (FPTR) - pointer to a routine that opens/activates the genie
  481.                 or player GUI. Returns the old window state (<>0 if the
  482.                 window was already opened else 0). Note: Make sure that
  483.                 you open on the right screen! See dtg_LockPubScreen() and
  484.                 dtg_UnLockPubScreen().
  485.  
  486.   DTP_Disappear (FPTR) - pointer to a routine that closes the GUI. This
  487.                 routine must return the old window state (0 if the window
  488.                 was already closed or <>0 if it was open).
  489.  
  490.   DTP_ModuleName (APTR) - address of a pointer to the real module name.
  491.                 The string must be null terminated. This Tag is for
  492.                 players only and is evaluated after InitPlay().
  493.  
  494.   DTP_FormatName (APTR) - address of a pointer to the real format name.
  495.                 The string must be null terminated. This Tag is for
  496.                 convert genies only and is evaluated after the Convert()
  497.                 function has been called.
  498.  
  499.   DTP_AuthorName (APTR) - not implemented yet!
  500.  
  501.   ;--- tags in revision 17 or higher (distributed as Release 2.07) ---
  502.  
  503.   DTP_InitNote (FPTR) - private, still under development!
  504.  
  505.   DTP_PlayTime (APTR) - not implemented yet!
  506.  
  507.  
  508.  
  509.   5.DELITRACKER SUPPORT FUNCTIONS
  510.  
  511.   DeliTracker provides some support functions that can be called from genies
  512.   and players. Every function is called like this:
  513.  
  514.         move.l  dtg_XXX(a5),a0          ; a5 must contain the base
  515.         jsr     (a0)
  516.  
  517.   All functions (exept dtg_SongEnd/dtg_SetTimer) use d0/d1/a0/a1 as scratch
  518.   register. A5 must contain the base (exept dtg_SongEnd/dtg_SetTimer).
  519.   Currently the following functions are available:
  520.  
  521.  
  522.   dtg_GetListData
  523.  
  524.         SYNOPSIS
  525.                 memory size = dtg_GetListData(number)
  526.                 A0     D0                     D0.l
  527.  
  528.         FUNCTION
  529.                 Returns the address and the length of a file that was
  530.                 loaded with dtg_LoadFile().
  531.  
  532.         INPUTS
  533.                 number - number of the file beginning with 0 for the file
  534.                          that was selected by the user.
  535.  
  536.         RESULT
  537.                 memory - startaddress of the files in memory, if error 0.
  538.                 size - length of the loaded file in bytes or 0 in case of
  539.                        an error
  540.  
  541.  
  542.   dtg_LoadFile
  543.  
  544.         SYNOPSIS
  545.                 success = dtg_LoadFile(name)
  546.  
  547.         FUNCTION
  548.                 Loads and decrunches the specified file to chipmemory.
  549.                 Note: this function automatically adds '.pp' to the
  550.                       filename.
  551.  
  552.         INPUTS
  553.                 name - store the filename in the internal buffer
  554.                        (dtg_PathArray contains a pointer to this buffer)
  555.  
  556.         RESULT
  557.                 success - success d0.l=0, else d0.l<>0.
  558.  
  559.  
  560.   dtg_CopyDir
  561.  
  562.         SYNOPSIS
  563.                 dtg_CopyDir()
  564.  
  565.         FUNCTION
  566.                 Copies the directory of the selected file at the end
  567.                 of the string, that dtg_PathArray points to.
  568.  
  569.  
  570.   dtg_CopyFile
  571.  
  572.         SYNOPSIS
  573.                 dtg_CopyFile()
  574.  
  575.         FUNCTION
  576.                 Copies the filename of the selected file at the end
  577.                 of the string, that dtg_PathArray points to.
  578.  
  579.  
  580.   dtg_CopyString
  581.  
  582.         SYNOPSIS
  583.                 dtg_CopyString(string)
  584.                                A0
  585.  
  586.         FUNCTION
  587.                 a0 contains the address of a string, which is copied at
  588.                 the end of the string that dtg_PathArray points to.
  589.  
  590.         INPUTS
  591.                 string - a0 contains the pointer to the string
  592.  
  593.  
  594.   dtg_AudioAlloc
  595.  
  596.         SYNOPSIS
  597.                 success = dtg_AudioAlloc()
  598.  
  599.         FUNCTION
  600.                 Allocates the audiochannels
  601.  
  602.         RESULT
  603.                 success - if we got them: d0.l=0, else d0.l<>0.
  604.  
  605.  
  606.   dtg_AudioFree
  607.  
  608.         SYNOPSIS
  609.                 dtg_AudioFree()
  610.  
  611.         FUNCTION
  612.                 Frees the audiochannels that were allocated with
  613.                 dtg_AudioAlloc.
  614.  
  615.  
  616.   dtg_StartInt
  617.  
  618.         SYNOPSIS
  619.                 dtg_StartInt()
  620.  
  621.         FUNCTION
  622.                 Starts the soundinterrupt. If DTP_Interrupt exists,
  623.                 DeliTracker starts the internal timer interrupt,
  624.                 else DTP_StartInt is called.
  625.  
  626.  
  627.   dtg_StopInt
  628.  
  629.         SYNOPSIS
  630.                 dtg_StopInt()
  631.  
  632.         FUNCTION
  633.                 Stops the soundinterrupt. If DTP_Interrupt exists,
  634.                 DeliTracker stops the internal timerinterrupt, else
  635.                 DTP_StopInt is called.
  636.  
  637.  
  638.   dtg_SongEnd
  639.  
  640.         SYNOPSIS
  641.                 dtg_SongEnd()
  642.  
  643.         FUNCTION
  644.                 Signals DeliTracker, that the module was played once.
  645.                 This function doesn't change any registers and is save
  646.                 to call from interrupts.
  647.  
  648.  
  649.   dtg_CutSuffix
  650.  
  651.         SYNOPSIS
  652.                 dtg_CutSuffix()
  653.  
  654.         FUNCTION
  655.                 Removes the suffix '.pp', '.im', '.xpk' at the end of the
  656.                 string, that dtg_PathArray points to.
  657.  
  658.  
  659.   ;------ extensions in revision 14 (distributed as Release 1.34)
  660.  
  661.   dtg_SetTimer
  662.  
  663.         SYNOPSIS
  664.                 dtg_SetTimer()
  665.  
  666.         FUNCTION
  667.                 Programs the timer with the value that is stored in
  668.                 dtg_Timer(a5). This function doesn't change any
  669.                 registers and is save to call from interrupts.
  670.  
  671.  
  672.   ;------ extensions in revision 15 (distributed as Release 1.37)
  673.  
  674.   dtg_WaitAudioDMA
  675.  
  676.         SYNOPSIS
  677.                 dtg_WaitAudioDMA()
  678.  
  679.         FUNCTION
  680.                 Waits a particular amount of time before returning.
  681.                 This amount of time is enough for the audio hardware
  682.                 to set new values. This function is only allowed if
  683.                 the internal timer-interrupt is used. Use it instead
  684.                 of the usual dbra or rasterline dma wait's in the
  685.                 replayer's interruptcode. This function doesn't change
  686.                 any registers.
  687.  
  688.  
  689.   ;------ extensions in revision 16 (distributed as release 2.01)
  690.  
  691.   dtg_LockScreen
  692.  
  693.         SYNOPSIS
  694.                 screen = dtg_LockScreen()
  695.                 D0
  696.  
  697.         FUNCTION
  698.                 Try to lock the screen on which DeliTracker is running.
  699.                 This is allways a pubscreen.
  700.  
  701.         RESULT
  702.                 Screenpointer in d0 or NULL on failure.
  703.  
  704.  
  705.   dtg_UnlockScreen
  706.  
  707.         SYNOPSIS
  708.                 dtg_UnlockScreen()
  709.  
  710.         FUNCTION
  711.                 this function unlocks DeliTracker's screen. Note: do not
  712.                 unlock a screen more times than you have locked it!
  713.  
  714.  
  715.   dtg_NotePlayer
  716.  
  717.         SYNOPSIS
  718.                 dtg_NotePlayer()
  719.  
  720.  
  721.         FUNCTION
  722.                 this call plays the notes specified in the current NoteStruct
  723.                 structure. This function call is not allowed if the active
  724.                 player doesn't have a valid NotePlayer structure.
  725.                 Note: This call is guaranteed to preserve all registers. It
  726.                 is save to call from interrupt, if the interrupt level is 4
  727.                 or lower.
  728.  
  729.         INPUTS
  730.                 current NoteStruct.
  731.  
  732.  
  733.   dtg_AllocListData
  734.  
  735.         SYNOPSIS
  736.                 memory = dtg_AllocListData(byteSize,Flags)
  737.                 D0                         D0.l     D1.l
  738.  
  739.  
  740.         FUNCTION
  741.                 This is the memory allocator function for module specific memory
  742.                 to be used by all players and genies. It provides a means of
  743.                 specifying that the allocation should be made in a memory area
  744.                 accessible to the chips, or accessible to shared system memory.
  745.                 If the allocation is successful, DeliTracker will keep track of
  746.                 the new block and dtg_GetListData()) will return the location and
  747.                 size of this block.
  748.  
  749.  
  750.         INPUTS
  751.                 byteSize - the size of the desired block in bytes.
  752.  
  753.                 Flags - flags that are passed through to AllocMem().
  754.  
  755.         RESULT
  756.                 A pointer to the newly allocated memory block is returned in d0.
  757.                 If there are no free memory regions large enough to satisfy the
  758.                 request, zero will be returned. The pointer must be checked
  759.                 for zero before the memory block may be used!
  760.  
  761.  
  762.   dtg_FreeListData
  763.  
  764.         SYNOPSIS
  765.                 dtg_FreeListData(memoryBlock)
  766.                                  A1
  767.  
  768.         FUNCTION
  769.                 Free a region of memory allocated with AllocListData(),
  770.                 returning it to the system pool from which it came.
  771.  
  772.         INPUTS
  773.                 memoryBlock - pointer of the memory block to free, may be NULL.
  774.  
  775.